package tcln.gxtx.client.utils.store;

import com.extjs.gxt.ui.client.data.ModelData;
import com.extjs.gxt.ui.client.store.Store;
import com.extjs.gxt.ui.client.widget.grid.GridView;

/**
 * A wrapper for {@link com.extjs.gxt.ui.client.store.Record} UPDATE action. Depending on the implementation of this
 * interface, several strategies may be applied to this action.
 * <p>
 * Basic usage of this updater is:
 * <ol>
 * <li>Creates an updater object. This updater cannot be created directly using <code>new</code> operator. Instead, use
 * {@link RecordUpdaterFactory} to perform this operation.
 * <li>Upon getting an updater, its owner store must be set in order to support other methods via
 * {@link #setStore(Store)}. Missing invoking this method results a {@link NullPointerException}.
 * <li>Then, a grid view may be optionally set for some implementations of this updater for specific purpose. This is
 * done via {@link #setGridView(GridView)}.
 * <li>Next, in the code requiring to use {@link com.extjs.gxt.ui.client.store.Record#set(String, Object)}, use
 * {@link #updateRecord(ModelData, String, Object)} to update changes.
 * <li>At the end of this code, invoke {@link #finishUpdating()} once.
 * <li>Method {@link #commitChanges(boolean)} can be optionally invoked to perform
 * {@link com.extjs.gxt.ui.client.store.Record#commit(boolean)}. However, this commission behaviour may be different
 * from one implementation to another one.
 * </ol>
 * 
 * 
 * @param <M>
 *            model data type.
 * @author Truong Chau Lien Ngoc (lienngoc@gmail.com)
 */
public interface RecordUpdater<M extends ModelData> {

    /**
     * Sets an owner grid/tree store for this updater.
     * 
     * @param store
     */
    void setStore(Store<M> store);

    /**
     * Sets a {@link GridView} for this updater. This information is not required by standard implementations of this
     * updater.
     * 
     * @param gridView
     */
    void setGridView(GridView gridView);

    /**
     * Updates given property of given modified model in given store with given new value.
     * 
     * @param modifiedModel
     * @param property
     * @param newValue
     */
    void updateRecord(M modifiedModel, String property, Object newValue);

    /**
     * Finishes the updating process for all properties in all modified records.
     * 
     * @param store
     */
    void finishUpdating();

    /**
     * Commits all changes made by {@link #updateRecord(Store, ModelData, String, Object)} invocations.
     * 
     * @param store
     * @param silent
     */
    void commitChanges(boolean silent);
}